home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / graphics / model3d.zip / XMS.DOC < prev   
Text File  |  1991-03-04  |  13KB  |  315 lines
  1.      XMS (eXtended Memory Specification) Unit For Turbo Pascal 6.0
  2.                               Version 1.0
  3.                           Written by Yuval Tal
  4.                                04-Mar-91
  5.  
  6. This program may be freely distributed for non-commercial, non-business,
  7. and non-governmental uses, provided this notice is attached with it.  My
  8. only request is that if you plan to use it regularly, let me know of know
  9. about it through e-mail or postal mail, so that I have an idea of how useful
  10. this program is (if you will add some cash to that letter it would be nice,
  11. ofcourse :-)). Also, if you have any problems, suggestions etc' please let
  12. me know.
  13.  
  14. InterNet:
  15.           nyyuval@weizmann.weizmann.ac.il
  16.                       or
  17.           yuvalt@wisdocs.weizmann.ac.il
  18.  
  19. Home address:
  20.           13 Glazer st.
  21.           Rehovot, 76283
  22.           Israel
  23.  
  24. Introduction
  25. ------------
  26. The primitive method of accessing the extended memory is by using the AT's
  27. BIOS interrupt 15h. These methods have several weaknesses which I will not
  28. describe here. At 1988 Microsoft, Intel, AST Research and Lotus Corp. made
  29. a more sophisticated use of extended memory under MS-DOS - eXtended Memory
  30. Specification (XMS). The XMS defines software interface for 80286, 80386
  31. and 80486 based PCs that allow real-mode application to use extended memory
  32. (EMB) and some areas of conventional memory which MS-DOS does not manage
  33. (UMB and HMA). Here is a figure which descirbes the memory:
  34.  
  35.       ┌─────────────────┐ 0K                \
  36.       │                 │                    |
  37.       │   Base Memory   │                    |
  38.       │                 │                    |   Conventional Memory
  39.       │                 │                    |
  40.       ├─────────────────┤ 640K               |
  41.       │  Upper Memory   │                    |
  42.       │  Blocks (UMB)   │                   /
  43.       ├─────────────────┤ 1024K (1MB)
  44.       │   High Memory   │                   \
  45.       │   Area  (HMA)   │                    |
  46.       ├─────────────────┤ 1088K              |
  47.       │                 │                    |
  48.       │                 │                    |
  49.       .                 .                    |   
  50.       .                 .                    |   Extended Memory
  51.       . Extended Memory .                    |   
  52.       │  Blocks  (EMB)  │                    |
  53.       │                 │                    |
  54.       │                 │                    |
  55.       │                 │                    |
  56.       │                 │                    |
  57.       │                 │                   /
  58.       └─────────────────┘ 16384K (16MB)
  59.  
  60. XMS defines function calls that allocate, release, resize memory blocks.
  61. The XMS also provides some control over the CPU's address line A20 which
  62. must be enabled inorder to read or write extended memory. An installable
  63. device driver that implements the XMS is called XMM (eXtended Memory Manager).
  64. The two most commonly used device drivers are:
  65.  
  66. 1. The one supplied by MicroSoft (HIMEM.SYS).
  67. 2. Quarterdeck's Extended Memory Manager (QEMM.SYS).
  68.  
  69. Using the XMS Unit you are able to call all the XMS functions from Turbo
  70. Pascal without having to worry about assembly or anything else. Here is a
  71. short and simple example of the XMS unit which copies the numbers 1 to 9 to
  72. the extended memory and then reads them from there:
  73.  
  74. Program XMSExample;
  75.  
  76. Uses
  77.   XMS;
  78.  
  79. Const
  80.   Numbers: Array [0..9] Of Byte = (0,1,2,3,4,5,6,7,8,9);
  81.  
  82. Var
  83.   Handler: Word;
  84.  
  85. Begin
  86.   Handler:=EMBGetMem(1);              {Allocate 1K from the extended memory}
  87.   MoveToEMB(Numbers,Handler,10);      {Move from conventional memory to}
  88.                                       {allocated extended memory}
  89.   MoveFromEMB(Handler,Numbers,10);    {Move from extended memory to}
  90.                                       {conventional memory}
  91.   EMBFreeMem(Handler);                {Release extended memory}
  92. End.
  93.  
  94. This example didn't do much it just demonstrated the ease of the XMS unit.
  95.  
  96. Procedures/Functions
  97. --------------------
  98. XMS comes with the source code so it is very easy to understand how the
  99. interface withe the XMM is done. The source code should be compiled on
  100. Turbo Pascal 6.0 since it uses the ASM command. Here is a list of all
  101. the procedures/function with the XMS unit contains:
  102.  
  103. +-------------------+
  104. | General functions |
  105. +-------------------+--------------------------------------------------------
  106.  
  107. Function XMMPresent: Boolean;
  108.  
  109. This function returns True is the extended memory manager device driver
  110. is installed in memory and active. True if installed, false if not installed.
  111.  
  112. -----------------------------------------------------------------------------
  113.  
  114. Function XMSErrorString(Error: Byte): String;
  115.  
  116. This functions translated the error code which is returned by all the
  117. procedures/functions in the unit from a number to a string. The error code is
  118. written to the global variable XMSError (byte). If XMSError is equal to 0
  119. than no error was encountered.
  120.  
  121. -----------------------------------------------------------------------------
  122.  
  123. Function XMSMemAvail: Word;
  124.  
  125. This function returns the total free extended memory in kilo-bytes.
  126.  
  127. -----------------------------------------------------------------------------
  128.  
  129. Function XMSMaxAvail: Word;
  130.  
  131. This function returns the largest free extended memory block in kilo-bytes.
  132.  
  133. -----------------------------------------------------------------------------
  134.  
  135. Function GetXMMVersion: Word;
  136.  
  137. This function returns the version of the extended memory manger device driver
  138. version. If the result is 500 then the version is 5.00.
  139.  
  140. -----------------------------------------------------------------------------
  141.  
  142. Function GetXMSVersion: Word;
  143.  
  144. This function returns the version of the extended memory specifications
  145. version. If the result is 200 then the version is 2.00.
  146.  
  147. +------------------------------------------------+
  148. | Extended memory blocks (EMB) related functions |
  149. +------------------------------------------------+--------------------------
  150.  
  151. Function EMBGetMem(Size: Word): Word;
  152.  
  153. This function allocated extended memory and returns a handler which is used
  154. by the other EMB commands to refer to this block. Size defines the size of
  155. the requested block in kilo-bytes.
  156.  
  157. -----------------------------------------------------------------------------
  158.  
  159. Procedure EMBFreeMem(Handle: Word);
  160.  
  161. This procedure releases allocated extended memory. Handle is a handle number
  162. which was given by EMBGetMem. Note: If a program fails to release its
  163. extended memory before it terminates, the memory becmoes unavailable to other
  164. programs until the system is restarted. Blocks may not be released while they
  165. are locked.
  166.  
  167. -----------------------------------------------------------------------------
  168.  
  169. Procedure EMBResize(Handle, Size: Word);
  170.  
  171. This procedure changes the size of a block. Handle is a handle number which
  172. was given by EMBGetMem. Size is the new size of the block. Blocks may not be
  173. resized while they are locked.
  174.  
  175. -----------------------------------------------------------------------------
  176.  
  177. Procedure MoveToEMB(Var Source; Handle: Word; BlockLength: LongInt);
  178.  
  179. This procedure moves data from the conventional memory to the extended
  180. memory. Source is a non-typed variable so any kind of data can be written
  181. there. Handle is a handle number given by EMBGetMem. BlockLength is the
  182. number of byes which should be moved. The state of the A20 line is preserved.
  183.  
  184. -----------------------------------------------------------------------------
  185.  
  186. Procedure MoveFromEMB(Handle: Word; Var Dest; BlockLength: LongInt);
  187.  
  188. This procedure moves data from the extended memory to the conventional
  189. memory. Dest is a non-typed variable so any kind of data can be written
  190. there. Handle is a handle number given by EMBGetMem. BlockLength is the
  191. number of byes which should be moved. The state of the A20 line is preserved.
  192.  
  193. -----------------------------------------------------------------------------
  194.  
  195. Function GetAvailEMBHandles: Byte;
  196.  
  197. This function returns the number of free handlers which are available.
  198.  
  199. -----------------------------------------------------------------------------
  200.  
  201. Function GetEMBLock(Handle: Word): Byte;
  202.  
  203. This function returns the lock count of a specified EMB. Handle is a handle
  204. number given by EMBGetMem. If the function returns 0 it means that the block
  205. is not locked.
  206.  
  207. -----------------------------------------------------------------------------
  208.  
  209. Function GetEMBSize(Handle: Word): Word;
  210.  
  211. This function returns the size of a specified EMB. Handle is a handle number
  212. given by EMBGetMem. The result is the size of the block in kilo-bytes.
  213.  
  214. -----------------------------------------------------------------------------
  215.  
  216. Function LockEMB(Handle: Word): LongInt;
  217.  
  218. This function locks a specified EMB. This fucntion is intended for use by
  219. programs which enable the A20 line and the access extended memory directly.
  220. The result is a 32-bit linear address of the locked block. Handle is a handle
  221. number given by EMBGetMem.
  222.  
  223. -----------------------------------------------------------------------------
  224.  
  225. Procedure UnlockEMB(Handle: Word);
  226.  
  227. This procedure unlocks previously locked blocks (by LockEMB). After the EMB
  228. is unlocked the 32-bit linear address returned by LockEMB becomes invalid and
  229. should not be used. Handle is a handle number given by EMBGetMem.
  230.  
  231. +---------------------------------------------+
  232. | Upper memory blocks (UMB) related functions |
  233. +---------------------------------------------+------------------------------
  234.  
  235. Function UMBGetMem(Size: Word; Var Segment: Word): Word;
  236.  
  237. This function allocates upper memory blocks. Size is the size of the block
  238. in paragraphs. Segment is retured by this function and it contains the
  239. segment base of the allocated block. The result of this function is the
  240. actual block size in paragraphs. In case of an error the result will be the
  241. size of the largest available block in paragraphs.
  242.  
  243. -----------------------------------------------------------------------------
  244.  
  245. Procedure UMBFreeMem(Segment: Word);
  246.  
  247. This procedure releases the memory that was allocated by UMBGetMem. Segment
  248. should contains the segment base of the block which should be released.
  249.  
  250. +--------------------------------------------+
  251. | High memory blocks (HMA) related functions |
  252. +--------------------------------------------+-------------------------------
  253.  
  254. Procedure HMAGetMem(Size: Word);
  255.  
  256. This function allocates high memory area (HMA). Size contains the the bytes
  257. which are needed. The maximum HMA allocation is 65520 bytes. The base address
  258. of the HMA is FFFF:0010h. If an application fails to release the HMA before it
  259. terminates, the HMA becmoes unavailable to the other programs until the
  260. system is restarted.
  261.  
  262. -----------------------------------------------------------------------------
  263.  
  264. Procedure HMAFreeMem;
  265.  
  266. This procedure releases the high memory area (HMA).
  267.  
  268. -----------------------------------------------------------------------------
  269.  
  270. Function GetHMA: Boolean;
  271.  
  272. This function obtains the status of the high memory area (HMA). If the result
  273. is true, HMA exists. If the result is false no HMA exists.
  274.  
  275. +-----------------------+
  276. | A20 related functions |
  277. +-----------------------+----------------------------------------------------
  278.  
  279. Function GetA20Status: Boolean;
  280.  
  281. This function returns the status of the A20 address line. If the result is
  282. true then the A20 line is enabled. If false, it is disabled.
  283.  
  284. -----------------------------------------------------------------------------
  285.  
  286. Procedure EnableLocalA20;
  287.  
  288. This procedure enables the A20 line and should only be used by programs that
  289. have successfully allocated the HMA. The A20 line should be disabled before
  290. the program releases control of the system.
  291.  
  292. -----------------------------------------------------------------------------
  293.  
  294. Procedure EnableGlobalA20;
  295.  
  296. This procedure disables the A20 line and should only be used by programs that
  297. have successfully allocated the HMA.
  298.  
  299. -----------------------------------------------------------------------------
  300.  
  301. Procedure EnableLocalA20;
  302.  
  303. This procedure enables the A20 line and should only be used by programs that
  304. do not own the HMA. The A20 line should be disabled before the program
  305. releases control of the system.
  306.  
  307. -----------------------------------------------------------------------------
  308.  
  309. Procedure DisableGlobalA20;
  310.  
  311. This procedure disables the A20 line and should only be used by programs that
  312. do not own the HMA.
  313.  
  314. -----------------------------------------------------------------------------
  315.